home *** CD-ROM | disk | FTP | other *** search
/ Apple Developer Connection Student Program / ADC Tools Sampler CD Disk 3 1999.iso / Metrowerks CodeWarrior / Java Support / Java_Source / Java2 / src / java / io / FileOutputStream.java < prev    next >
Encoding:
Java Source  |  1999-05-28  |  9.6 KB  |  264 lines  |  [TEXT/CWIE]
  1. /*
  2.  * @(#)FileOutputStream.java    1.35 98/09/24
  3.  *
  4.  * Copyright 1994-1998 by Sun Microsystems, Inc.,
  5.  * 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
  6.  * All rights reserved.
  7.  *
  8.  * This software is the confidential and proprietary information
  9.  * of Sun Microsystems, Inc. ("Confidential Information").  You
  10.  * shall not disclose such Confidential Information and shall use
  11.  * it only in accordance with the terms of the license agreement
  12.  * you entered into with Sun.
  13.  */
  14.  
  15. package java.io;
  16.  
  17.  
  18. /**
  19.  * A file output stream is an output stream for writing data to a 
  20.  * <code>File</code> or to a <code>FileDescriptor</code>. What files 
  21.  * are available or may be created depends on the host environment.
  22.  *
  23.  * @author  Arthur van Hoff
  24.  * @version 1.35, 09/24/98
  25.  * @see     java.io.File
  26.  * @see     java.io.FileDescriptor
  27.  * @see     java.io.FileInputStream
  28.  * @since   JDK1.0
  29.  */
  30. public
  31. class FileOutputStream extends OutputStream
  32. {
  33.     /**
  34.      * The system dependent file descriptor. The value is
  35.      * 1 more than actual file descriptor. This means that
  36.      * the default value 0 indicates that the file is not open.
  37.      */
  38.     private FileDescriptor fd;
  39.  
  40.     /**
  41.      * Creates an output file stream to write to the file with the 
  42.      * specified name. A new <code>FileDescriptor</code> object is 
  43.      * created to represent this file connection.
  44.      * <p>
  45.      * First, if there is a security manager, its <code>checkWrite</code> 
  46.      * method is called with <code>name</code> as its argument.
  47.      * <p>
  48.      * If the file exists but is a directory rather than a regular file, does
  49.      * not exist but cannot be created, or cannot be opened for any other
  50.      * reason then a <code>FileNotFoundException</code> is thrown.
  51.      *
  52.      * @param      name   the system-dependent filename
  53.      * @exception  FileNotFoundException  if the file exists but is a directory
  54.      *                   rather than a regular file, does not exist but cannot
  55.      *                   be created, or cannot be opened for any other reason
  56.      * @exception  SecurityException  if a security manager exists and its
  57.      *               <code>checkWrite</code> method denies write access
  58.      *               to the file.
  59.      * @see        java.lang.SecurityManager#checkWrite(java.lang.String)
  60.      */
  61.     public FileOutputStream(String name) throws FileNotFoundException {
  62.     this(name, false);
  63.     }
  64.  
  65.     /**
  66.      * Creates an output file stream to write to the file with the specified
  67.      * <code>name</code>.  If the second argument is <code>true</code>, then
  68.      * bytes will be written to the end of the file rather than the beginning.
  69.      * A new <code>FileDescriptor</code> object is created to represent this
  70.      * file connection.
  71.      * <p>
  72.      * First, if there is a security manager, its <code>checkWrite</code> 
  73.      * method is called with <code>name</code> as its argument.
  74.      * <p>
  75.      * If the file exists but is a directory rather than a regular file, does
  76.      * not exist but cannot be created, or cannot be opened for any other
  77.      * reason then a <code>FileNotFoundException</code> is thrown.
  78.      * 
  79.      * @param     name        the system-dependent file name
  80.      * @param     append      if <code>true</code>, then bytes will be written
  81.      *                   to the end of the file rather than the beginning
  82.      * @exception  FileNotFoundException  if the file exists but is a directory
  83.      *                   rather than a regular file, does not exist but cannot
  84.      *                   be created, or cannot be opened for any other reason.
  85.      * @exception  SecurityException  if a security manager exists and its
  86.      *               <code>checkWrite</code> method denies write access
  87.      *               to the file.
  88.      * @see        java.lang.SecurityManager#checkWrite(java.lang.String)
  89.      * @since     JDK1.1
  90.      */
  91.     public FileOutputStream(String name, boolean append)
  92.         throws FileNotFoundException
  93.     {
  94.     SecurityManager security = System.getSecurityManager();
  95.     if (security != null) {
  96.         security.checkWrite(name);
  97.     }
  98.     fd = new FileDescriptor();
  99.     if (append) {
  100.         openAppend(name);
  101.     } else {
  102.         open(name);
  103.     }
  104.     }
  105.  
  106.     /**
  107.      * Creates a file output stream to write to the file represented by 
  108.      * the specified <code>File</code> object. A new 
  109.      * <code>FileDescriptor</code> object is created to represent this 
  110.      * file connection.
  111.      * <p>
  112.      * First, if there is a security manager, its <code>checkWrite</code> 
  113.      * method is called with the path represented by the <code>file</code> 
  114.      * argument as its argument.
  115.      * <p>
  116.      * If the file exists but is a directory rather than a regular file, does
  117.      * not exist but cannot be created, or cannot be opened for any other
  118.      * reason then a <code>FileNotFoundException</code> is thrown.
  119.      *
  120.      * @param      file               the file to be opened for writing.
  121.      * @exception  FileNotFoundException  if the file exists but is a directory
  122.      *                   rather than a regular file, does not exist but cannot
  123.      *                   be created, or cannot be opened for any other reason
  124.      * @exception  SecurityException  if a security manager exists and its
  125.      *               <code>checkWrite</code> method denies write access
  126.      *               to the file.
  127.      * @see        java.io.File#getPath()
  128.      * @see        java.lang.SecurityException
  129.      * @see        java.lang.SecurityManager#checkWrite(java.lang.String)
  130.      */
  131.     public FileOutputStream(File file) throws IOException {
  132.     this(file.getPath());
  133.     }
  134.  
  135.     /**
  136.      * Creates an output file stream to write to the specified file 
  137.      * descriptor, which represents an existing connection to an actual 
  138.      * file in the file system.
  139.      * <p>
  140.      * First, if there is a security manager, its <code>checkWrite</code> 
  141.      * method is called with the file descriptor <code>fdObj</code> 
  142.      * argument as its argument.
  143.      *
  144.      * @param      fdObj   the file descriptor to be opened for writing.
  145.      * @exception  SecurityException  if a security manager exists and its
  146.      *               <code>checkWrite</code> method denies
  147.      *               write access to the file descriptor.
  148.      * @see        java.lang.SecurityManager#checkWrite(java.io.FileDescriptor)
  149.      */
  150.     public FileOutputStream(FileDescriptor fdObj) {
  151.     SecurityManager security = System.getSecurityManager();
  152.     if (fdObj == null) {
  153.         throw new NullPointerException();
  154.     }
  155.     if (security != null) {
  156.         security.checkWrite(fdObj);
  157.     }
  158.     fd = fdObj;
  159.     }
  160.  
  161.     /**
  162.      * Opens a file, with the specified name, for writing.
  163.      * @param name name of file to be opened
  164.      */
  165.     private native void open(String name) throws FileNotFoundException;
  166.  
  167.     /**
  168.      * Opens a file, with the specified name, for appending.
  169.      * @param name name of file to be opened
  170.      */
  171.     private native void openAppend(String name) throws FileNotFoundException;
  172.  
  173.     /**
  174.      * Writes the specified byte to this file output stream. Implements 
  175.      * the <code>write</code> method of <code>OutputStream</code>.
  176.      *
  177.      * @param      b   the byte to be written.
  178.      * @exception  IOException  if an I/O error occurs.
  179.      */
  180.     public native void write(int b) throws IOException;
  181.  
  182.     /**
  183.      * Writes a sub array as a sequence of bytes.
  184.      * @param b the data to be written
  185.      * @param off the start offset in the data
  186.      * @param len the number of bytes that are written
  187.      * @exception IOException If an I/O error has occurred.
  188.      */
  189.     private native void writeBytes(byte b[], int off, int len) throws IOException;
  190.  
  191.     /**
  192.      * Writes <code>b.length</code> bytes from the specified byte array 
  193.      * to this file output stream. 
  194.      *
  195.      * @param      b   the data.
  196.      * @exception  IOException  if an I/O error occurs.
  197.      */
  198.     public void write(byte b[]) throws IOException {
  199.     writeBytes(b, 0, b.length);
  200.     }
  201.  
  202.     /**
  203.      * Writes <code>len</code> bytes from the specified byte array 
  204.      * starting at offset <code>off</code> to this file output stream. 
  205.      *
  206.      * @param      b     the data.
  207.      * @param      off   the start offset in the data.
  208.      * @param      len   the number of bytes to write.
  209.      * @exception  IOException  if an I/O error occurs.
  210.      */
  211.     public void write(byte b[], int off, int len) throws IOException {
  212.     writeBytes(b, off, len);
  213.     }
  214.  
  215.     /**
  216.      * Closes this file output stream and releases any system resources 
  217.      * associated with this stream. This file output stream may no longer 
  218.      * be used for writing bytes. 
  219.      *
  220.      * @exception  IOException  if an I/O error occurs.
  221.      */
  222.      public native void close() throws IOException;
  223.  
  224.     /**
  225.      * Returns the file descriptor associated with this stream.
  226.      *
  227.      * @return  the <code>FileDescriptor</code> object that represents 
  228.      *          the connection to the file in the file system being used 
  229.      *          by this <code>FileOutputStream</code> object. 
  230.      * 
  231.      * @exception  IOException  if an I/O error occurs.
  232.      * @see        java.io.FileDescriptor
  233.      */
  234.      public final FileDescriptor getFD()  throws IOException {
  235.     if (fd != null) return fd;
  236.     throw new IOException();
  237.      }
  238.     
  239.     /**
  240.      * Cleans up the connection to the file, and ensures that the 
  241.      * <code>close</code> method of this file output stream is
  242.      * called when there are no more references to this stream. 
  243.      *
  244.      * @exception  IOException  if an I/O error occurs.
  245.      * @see        java.io.FileInputStream#close()
  246.      */
  247.     protected void finalize() throws IOException {
  248.      if (fd != null) {
  249.          if (fd == fd.out || fd == fd.err) {
  250.          flush();
  251.          } else {
  252.          close();
  253.          }
  254.      }
  255.     }
  256.  
  257.     private static native void initIDs();
  258.     
  259.     static {
  260.     initIDs();
  261.     }
  262.  
  263. }
  264.